Overview

agentty is an ADE (Agentic Development Environment) for structured, controllable AI-assisted software development. This project is built using agentty itself, including the docs and docs-site you are reading.

It runs AI coding agents in dedicated AI sessions.

What Agentty Provides🔗

When you start a session, Agentty does the operational heavy lifting for workflow safety:

  • Spawns a clean worktree branch for every live session.
  • Runs agent-driven edits in isolation from your base branch.
  • Keeps terminal output, diffs, and generated changes in one reviewable stream.
  • Keeps already-published session branches synced after later completed turns.

Typical Flow🔗

  1. Open a repository and start agentty.
  2. Press a and choose Regular, Draft, or Stacked when an eligible parent session is selected.
  3. For regular sessions, type the first prompt and press Enter to start immediately.
  4. For draft sessions, stage one or more draft messages, then press s to start the bundle.
  5. For stacked drafts, stage messages while the parent is still under review, then start the draft after the parent merges and the child is restacked onto the base branch.
  6. Let the agent modify files in its worktree.
  7. Review the diff (d) and decide to apply or discard.

Worktree Isolation🔗

Every session runs in its own git worktree, created automatically when the live session starts:

  • The worktree branch is named wt/<hash>, where <hash> is derived from the session ID.
  • The branch starts from whichever local branch was active when you launched agentty. If local main is behind origin/main, the session still starts from local main.
  • Regular sessions create the worktree as soon as you start the first prompt. Draft sessions delay worktree creation until you press s to start the staged bundle. Stacked drafts are based on the parent session branch, but they stay blocked until the parent merges; cancellation of the parent also cancels the stacked draft.
  • All agent edits happen inside the worktree, keeping your base branch untouched until you explicitly merge.
  • Before each turn, Agentty verifies that the session folder still exists, is on its expected wt/<hash> branch, and resolves to a linked worktree rather than the main checkout. It also compares the main checkout's tracked-file git status before and after the turn and adds a transcript warning if that checkout changed. Merge and sync actions still require a clean main checkout before they start.
  • If worktree creation fails (e.g., git is not installed or permissions are insufficient), session creation fails atomically and displays an error.

Worktrees are stored under ~/.agentty/wt/ and are cleaned up automatically when a session reaches Done or Canceled, or when you delete a session.

Auto-Update🔗

Agentty checks npmjs for newer versions at startup and automatically installs updates in the background. Progress is shown in the status bar. The new version takes effect on next launch. Use --no-update to disable automatic updates.

Key Concepts🔗

| Concept | Description | |---------|-------------| | Agent | An external AI CLI backend (Gemini, Claude, or Codex) that performs coding work. See Agents & Models. | | Session | An isolated unit of work: one prompt, one worktree branch, one reviewable diff. See Workflow and Keybindings. | | Project | A git repository registered in Agentty. Select between projects with the Projects tab. | | Diff view | Press d in a review-state session to see exactly what the agent changed. |

Next Steps🔗

  • Installation — install Agentty and run it for the first time.
  • Agents & Models — configure backends and choose models.
  • Workflow — learn the interface layout and session lifecycle.
  • Keybindings — learn the keyboard shortcuts for each view.